跳到主要内容

如果你主要做“运行时换图”，优先使用 Image Data Binding。
见：/docs/Runtimes/Data Binding

概览（Overview）

Rive 文件中的字体、图片、音频等资源可以：

  • 随 .riv 一起内嵌
  • 通过 Rive CDN 托管
  • 由应用侧运行时动态提供

合理选择资源策略可以平衡：

  • 文件体积
  • 首屏速度
  • 网络请求次数
  • 动态替换能力

编辑器导出模式（Export Options）

在编辑器 Assets 面板可配置：

1) Embedded（内嵌）​

  • 资源直接写入 .riv
  • 运行时无需额外处理
  • 但可能增大文件体积（尤其字体）

Embedded 是默认选项。

2) Hosted（托管）​

  • 资源不写入 .riv，由 Rive CDN 提供
  • 运行时可自动拉取
  • .riv 体积更小
  • 但会增加额外网络请求

3) Referenced（引用）​

  • 资源不内嵌
  • 由你的应用在运行时加载并注入
  • 最灵活，适合：
    • 多分辨率按设备切换
    • 按语言动态替换字体
    • 复用业务侧已有资源

典型收益场景

  • 保持 .riv 轻量
  • 动态下发不同资源版本
  • 预加载资源减少播放时抖动
  • 多个 .riv 共享同一资源实例

处理 Referenced Assets 的通用流程

  1. runtime 解析到外部资源占位
  2. 回调把 asset 元数据和 bytes（若有）传给你
  3. 你决定：
    • true：由应用侧处理（自行加载/解码/注入）
    • false：交回 runtime 继续处理（例如 Hosted）

关键是“是否接管”的布尔返回语义。

各 Runtime 用法（摘要）

Web / React​

通过 assetLoader 回调处理资源：

assetLoader: (asset, bytes) => boolean

常见策略：

  • 如果 asset.cdnUuid 存在或 bytes 已有，返回 false
  • 若是 Referenced 字体/图片，应用侧加载并 asset.decode(...) 后返回 true

Flutter​

在 File.asset(...) / File.url(...) 中提供 assetLoader：

final file = await File.asset(
  'assets/x.riv',
  riveFactory: Factory.rive,
  assetLoader: (asset, bytes) {
    // true: 你处理
    // false: runtime 处理
    return false;
  },
);

React Native（新版）​

通过 useRiveFile(..., { referencedAssets }) 提供映射：

const { riveFile } = useRiveFile(require('./x.riv'), {
  referencedAssets: {
    'Inter-594377': { source: require('./Inter.ttf') },
    'referenced-image-2929282': { source: { uri: 'https://example.com/a.png' } },
  },
});

Apple​

新版可通过 Worker 全局资源 API：

  • decodeFont/decodeImage/decodeAudio
  • addGlobal*Asset(name: ...)

用于在 worker 范围共享资源。

Android​

可通过自定义 AssetLoader（Legacy）接管；Compose 新链路建议结合新 API 与资源预加载策略。

Image CDN 注意事项

有些 CDN 支持按设备能力动态转码/裁剪。
接入时注意请求头 Accept，且确认输出格式在 Rive 支持范围内。

Rive 常用图片格式：

  • jpeg
  • png
  • webp

实践建议（Best Practices）

  1. 默认先用 Embedded 快速落地
  2. 文件过大或需动态替换时，再切 Referenced
  3. 跨页面高频复用资源时做缓存
  4. 字体优先建立统一 fallback + 资源管理策略
  5. 为 asset loader 增加失败兜底（日志 + 默认资源）

相关文档